# Chapter 17: Custom Logging

Helix Universal Server's custom logging feature allows you to monitor specific types of events and information that occur on Helix Universal Server. You can thereby create reports about any type of activity you choose. This chapter explains how to use the custom logging feature, which supplements the main log files described in Chapter 16.

# Understanding Custom Logging

Custom logging is a highly flexible feature that allows you to gather the exact information you want, reporting it at any time to different outputs such as the screen or a text file. You can use this feature to gather information about current Helix Universal Server client connections, for example. Custom logging is designed to supplement the access and error logging described in Chapter 16, but you may find that custom logging is adequate for all of your logging requirements.

## The Helix Universal Server Registry

To get information for reports, custom logging relies on information stored in the Helix Universal Server registry, which is distinct from the main registry on Windows operating systems. The registry contains information about most aspects of Helix Universal Server. Although the registry is an extension of Helix Administrator, there is no link to it from any Helix Administrator page. However, you can display the registry by opening the following URL in a browser:

    http://address:AdminPort/admin/regview.html

### Registry Variables

The Helix Universal Server registry stores information in variables such as `LiveConnections.Count`. Each variable reports a specific type of value or setting, from real-time data on client connections and server health, to configuration and license information. When you create a custom logging template, you add variables to your report by selecting them from a pop-up HTML list. Within a report template, variables are always preceded and followed by percent signs, as in `%LiveConnections.Count%`.

### Global Variables

Through the variables list, you can also choose global variables, such as the time of day, that are derived from the operating system rather than extracted from the Helix Universal Server registry. The following table lists the global variables that you can include in reports.

Global Variables
Variable | Description
--- | ---
`%Date%` | Indicates the current date in the format `MM/DD/YY`.
`%Time%` | Provides the current time of day in the local time zone in the format `HH:MM:SS`.
`%GMTime%` | Displays the current Greenwich Mean Time in the format `HH:MM:SS`.
`%TZDiff%` | Indicates the difference between local time and Greenwich Mean Time. For example, the output for Pacific Standard Time is `-0800`.
`%Hour%` | Displays the current hour by local time zone in the format `HH`.
`%Min%` | Indicates current minute in the format `MM`.
`%Sec%` | Adds the current second in the format `SS`.
`%%` | Creates a percent sign (`%`).

## Template Types

You add the registry variables that you want to track to a report template, which defines how often the selected information is reported, as well as where the report is delivered, such as to a file or to the console. You can use three types of templates:

- Interval

Interval templates log information at regular intervals, such as every hour. You can define exactly how much time elapses between report output. Interval reports are useful for producing regular status reports about Helix Universal Server health, for example.

- Watch

With a watch template, you can set a watch on a certain variable, or group of variables, generating a report when information changes. A watch template is useful for reporting errors, for example, because a report is generated only when an error occurs.

- Session

As system activity occurs, Helix Universal Server dynamically adds and deletes variables from its registry. When a media player requests a clip, for example, Helix Universal Server creates a unique registry entry for that player, storing information such as the player address and the requested URL. A session template reports on this dynamic activity as it happens.

| For More Information: See "Using Session Templates" for more information about these templates.

## Report Formats

Through the report template, you format a report, adding boilerplate text around selected variables if you wish. For example, you might create an entry like the following:

    With a total of %LiveConnections.Count% player connections, Helix Universal Server
    is using %Server.Bandwidth.Output% bits per second of bandwidth.

In this example, `%LiveConnections.Count%` and `%Server.Bandwidth.Output%` are variables, and the rest of the text is boilerplate. When Helix Universal Server generates the report, it replaces the variable entries with values from its registry. The resulting report looks like this:

    With a total of 50 player connections, Helix Universal Server
    is using 2,800,000 bits per second of bandwidth.

# Using Session Templates

A session template reports on dynamically added and deleted registry variables. Helix Universal Server creates registry variables when media players, encoders, transmitters, and other components connect to it. These variables store information about the component. Using a session template, you can create a report when one of these components connects, disconnects, or both. This lets you record statistics about each media player, for example, such as the player's IP address, its request URL, its bandwidth, and so on.

## Choosing a Watch Type

When you create a session template, you select a watch type, which specifies the type of component connection that generates the report. The following table describes the possible values that you can choose.

Watch Types
Watch Type Value | Registry Values Watched
--- | ---
`Client Session [Client.Session]` | Client connections.
`Client Stream [Client.Session.Stream.*]` | Individual media player streams.
`Broadcast Receiver [BroadcastReceiver.Statistics]` | Splitting receivers.
`Broadcast Transmitter [BroadcastDistribution.Statistics]` | Splitting transmitters.
`Broadcast [LiveConnections]` | Live connections.
`Broadcast Archiver [LiveArchiving.Archiver]` | Live broadcast archiving.
`Distributed Licensing[DistributedLicensing. Publishers.Subscribers]` | Distributed licensing.

For example, if you choose `Client Session [Client.Session]` as the watch type, you can generate a report every time a client connects or disconnects. In this case, clients can be media players requesting clips, as well as browsers displaying Helix Administrator HTML pages. In your report, you then choose which registry variables from that client connection you want to log.

| Tip: The section "Creating a Client Statistics Log" provides an example of how to gather client statistics.

## Selecting the Output Format Type

For each session template, you can choose whether to generate the report when the watched component connects, when it disconnects, or both. When you set up the template, you choose an output format from a pull-down list:

`Session Added Output Format` | Generate a report with the specified variables when the watched component connects.
`Session Deleted Output Format` | Generate a report with the specified variables when the component disconnects.

The two output formats allow you to report on different variables when a component session begins, then when it ends. When a client connects, for example, you may want to record several variables, including the client's IP address, request URL, streaming protocol, transport protocol, and so on. When it disconnects, though, you might want to record just the time and IP address.

# Defining Output Methods

The custom logging output methods determine how Helix Universal Server publishes the report. There are several options, and you can select multiple delivery methods for each custom log report. Additionally, multiple report templates can write to the same output, such as the same file. Most outputs require configuration. For example, if you send your report to a file and a local TCP port, you specify a file name and a port number.

## Console

The `Std Error` (Standard Error) and `Std Out` (Standard Output) options both publish the report to the command line console. No configuration is required.

## File

When you select the `File` output method, Helix Universal Server publishes the report to a text file, continuously appending new results to the end of the file unless you set up log rolling. You configure the following variables:

`File name` | The log file name. The default location is the main Helix Universal Server installation directory. You can specify a relative or absolute path using the syntax appropriate for your operating system.
`Log Rolling Frequency` | How many hours, days, weeks, or months pass before a new log file is created (optional).
`Log Rolling Size` | Maximum size in Megabytes that the log file can become before a new file is created (optional).

### Using Log File Rolling

Log rolling is optional, but recommended if you expect to report statistics frequently. If multiple templates write to the same file log file, define log rolling in just one template.

#### Log Rolling Methods

Generally, you limit log files by frequency or size. You can select both methods, however, to create log files according to the first limit reached. For example, you can create a new log file whenever the preceding file reaches 10 Megabytes in size, or has recorded 3 days of activity, whichever comes first.

#### Timestamps

When you implement log rolling, Helix Universal Server appends a timestamp to the end of the file name to indicate when the file was created. Suppose that you specify the file name `serverstats.txt`. Your log directory may contain several files with the same base file name, but each with a unique timestamp that looks like this:

    serverstats.txt.20020622134953

The timestamp is in the format `YYYYMMDDHHMMSS`, using a 24-hour clock. Hence, the file in the preceding example was created on June 22, 2002, at 1:49.53 P.M.

## HTTP Post

With the `HTTP Post` method, Helix Universal Server publishes the report to a Common Gateway Interface (CGI) program. You configure the following variables:

`URL` | URL location of the CGI program.
`Port` | Number of the HTTP port on the Web server receiving the log.

## TCP Broadcast

The `Outbound TCP` and `Inbound TCP` output destinations let you send the report to an application listening on a specific TCP port. The `Outbound TCP` method publishes the log on a remote computer. For this method, you configure the following variables:

`Destination` | Host name or IP address of the computer that receives the log.
`Port` | Number of an open port on the specified computer.

The `Inbound TCP` method publishes the log on the local computer. You configure the following variable:

`Port` | Number of an open port on the local computer.

## UDP Broadcast

The `Outbound UDP` and `Multicast UDP` methods publish the report to a UDP socket on a remote computer using unicast or multicast UDP, respectively. You configure the following variables:

`Destination` | Host name or IP address of the computer where the report should be published. For `Multicast UDP`, enter a Class D IP multicast address.
`Port` | Number of an open port on the specified computer.

## UNIX Pipe and System Log

On UNIX operating systems, the `Pipe` and `Syslog` methods make the log available to another process, or publish the information to the system log, respectively. For `Pipe`, you configure the following variable:

`Command` | Pipe command to the application or script where the information can be post-processed.

For `Syslog`, you choose one the following priorities, each of which corresponds to an entry type in the UNIX system log:

- `LOG_EMERG`

- `LOG_ALERT`

- `LOG_CRIT`

- `LOG_ERR`

- `LOG_WARNING`

- `LOG_NOTICE`

- `LOG_INFO`

- `LOG_DEBUG`

## Windows NT Event Log

If you choose `NT Event Log`, Helix Universal Server publishes the report to the event log that corresponds to the priority selected. Each option corresponds to an entry type in the Windows NT Event Log:

- `LOG_ERR`

- `LOG_WARNING`

- `LOG_INFO`

# Creating Logging Templates

The following procedure explains how to create a new custom logging template, or modify an existing one. You'll need to be familiar with the information in the preceding sections to set up your custom template. Preconfigured templates are ready to use, but must be turned on. These templates are described in the section "Using the Preconfigured Templates".

| To create or modify a custom logging template:

1. Click Logging & Monitoring>Custom Logging.

2. To create a new template, click the "+" icon in the Templates area, and edit the name in the Template Name box. This name is for your reference only. To select an existing template, highlight its name in the Templates area.

3. In the Template Type list box, select `Watch`, `Session`, or `Interval` to set the overall type of template. The option you choose affects other options that appear on the page, as described in Step 7 through Step 9.

| For More Information: See "Template Types".

4. From the Template Status box, select `On` or `Off` to enable or disable the custom logging report, respectively. An existing template starts or stops reporting as soon as you change its status and click Apply.

5. Optionally, you can enter a description in the Template Description box. This is for your own reference only, but is highly recommended.

6. You next select one or more output types for the report to determine where Helix Universal Server sends the report information:

1. Select an output type from Add Output Type pull-down list.

2. Optionally, edit the name in the Output Name box. This name is for your reference only.

3. For the selected output type, enter the necessary configuration parameters, as described in "Defining Output Methods".

7. If you chose a `Watch` template in Step 3, follow this step. Otherwise, skip to the next step. Click `Property List` in the Watches area. In the list that appears, choose the variable or variables that you want to watch for changes.

| Note: Place each watched variable on a separate line in the Watches list. Helix Universal Server determines which variables to watch by matching the string that appears on each line of the Watches list.

The optional minimum and maximum output intervals for the `Watch` template let you generate the report at regular intervals. If you do not define either field, Helix Universal Server creates the report only when a watched registry variable changes:

- Minimum Output Interval

This field holds a number in the format `HH:MM:SS` that defines the smallest possible time that must pass between log outputs. Changes to the watched variables are not reported until the minimum interval has elapsed. If you set `00:05:00`, for example, watched variables that change are reported every five minutes. If no watched variable changes its value in five minutes, though, the report is not created until a variable changes, or the maximum interval is reached.

- Maximum Output Interval

This entry contains a number in the format `HH:MM:SS` that defines the longest possible time allowed to pass before the report output is generated. Changes to variables being watched will generate the report output even if the maximum interval has not been reached, however. If you set `01:00:00`, for instance, and no watched variable changes within an hour after the last report, Helix Universal Server generates the report when the hour elapses.

8. If you chose `Session` in Step 3, select the appropriate watch type from the Watch Type list box. Otherwise, skip to the next step. As described in "Choosing a Watch Type", the watch type you select determines which dynamic event triggers the report output.

9. If you chose `Interval` in Step 3, set the appropriate combination of hour, minute, and seconds for the report interval in the Output Interval boxes. If you leave a box blank, the setting for that box is considered to be 0.

10. In the Output Format area, click Property List to pick the variables from the Helix Universal Server registry included in the template. If you're setting up a `Session` Template, you can specify up to two output formats, one for Session Added Output Format, and one for Session Deleted Output Format.

1. In the property list window, navigate to the variable that you want to include in the template.

2. When you click on a variable, a string identifying that variable appears in the Output Format text box. Helix Universal Server reports values for variables in the exact order the variables appear in the text box. To organize the order of variables, cut and paste them in the order that you want them to appear in your report.

| Tip: A variable added to the Output Format text box is surrounded by percentage signs (`%Server.Bandwidth.Output%`). If you reorganize the order of the variables, make sure to include the percent signs that surround each variable name.

3. Optionally, format the report output by adding boilerplate text.Two tags help with formatting the output sting. Use a `\n` tag to move output to a new line. Carriage returns you enter in the box are also recognized as new lines. Use a `\t` tag to insert a tab.

11. Click Apply.

# Sample Templates

This section explains how to use the preconfigured templates that come with Helix Universal Server. It then provides an example of setting up your own template to log client statistics.

## Using the Preconfigured Templates

Helix Universal Server comes preconfigured with three templates that illustrate the interval, watch, and session template types. Each template reports output to the console, but is turned off initially. To use a template, you must enable it and, optionally, customize it by changing the output destination or modifying the reporting variables. You can also ignore these templates and create your own. The following sections explain these templates.

### Errors Template

The preconfigured `Errors` template is a watch-type template. Whenever Helix Universal Server encounters an error, the `Errors` template writes the message to the console. You may want to modify this template to send the output to a file, for example. As well, you can establish minimum and maximum intervals instead of reporting each time an error occurs.

### Extended Logging Template

The preconfigured `Extended Logging` template is an example of a session template. It gathers information about client sessions, including media players and Helix Administrator activity, and publishes the report to the console when a client session ends. A single line of the report output looks like this:

    09:55:28 127.0.0.1 RTSP GET real9video.rm RealMedia Player Version 6.0.9.1349 (win32)

### Server Stats Template

The preconfigured `Sever Stats` template is an example of an interval template. It is designed to send basic server statistics to the output console every hour. Optionally, you can modify the variables it reports, write the information to a file, or change its boilerplate text. The report output looks like this:

    Server Stats (06/17/02 10:33:52)
        Uptime: 1234274 seconds
        CPU Percent Usage: 5
        Players Connected: 32
        Players Connected in the Last 10 Seconds: 2
        Players Connected by Protocol: 0 PNA, 22 RTSP, 10 MMS, 0 HTTP (0 Cloaked)
        Players Connected by Transport: 0 TCP, 32 UDP, 0 MCast
        Total Subscribed Bandwidth Output: 9385984 bps
        Total Actual Bandwidth Output: 9244432 bps
        Average Bandwidth Output Per Player: 293312 bps
        Memory Stats: 14294824 Bytes In Use

## Creating a Client Statistics Log

This example illustrates how to log information about each client request, including media players requesting clips and browsers requesting Helix Administrator pages. This sample template also logs information when each client disconnects. In your template, you would set up the following basic parameters:

Template Name: | `any`
Template Type: | `Session`
Template Status: | `on`
Template Outputs: | `any`
Watch Type: | `Client Session [Client.Session]`

### Connection Statistics Boilerplate and Variables

For Session Added Output Format, you define the report information you want to collect when a client connects. You create a report using boilerplate text and variables chosen from the pop-up property list. Note that `\n` adds a new line to the report. You can also use `\t` to insert tabs. Here's an example:

    \n\n****CLIENT REQUEST****
    Date and Time: %Date%, %Hour%:%Min%.%Sec%
    **CLIENT INFORMATION**
    Type: %Client.*.User-Agent%
    Address: %Client.*.Addr%
    Total Bandwidth: %Client.*.Bandwidth%
    Preferred Language: %Client.*.Language%
    **CLIP INFORMATION**
    Requested URL: %Client.*.Session.*.PlayerRequestedURL%
    Clip Size in Bytes: %Client.*.Session.*.FileSize%
    Title: %Client.*.Session.*.FileHeader.Title%
    Author: %Client.*.Session.*.FileHeader.Author%
    Copyright: %Client.*.Session.*.FileHeader.Copyright%
    Stream Count: %Client.*.Session.*.FileHeader.StreamCount%
    **TRANSPORT INFORMATION**
    Protocol: %Client.*.Protocol%
    Port: %Client.*.Port%
    UDP used (0=no, 1=yes): %Client.*.IsUDP%

### Disconnect Statistics Boilerplate and Variables

For Session Deleted Output Format, you define the report information you want to collect when a client disconnects. Here's an example:

    \n\n****CLIENT DISCONNECT****
    Date and Time: %Date%, %Hour%:%Min%.%Sec%
    Type: %Client.*.User-Agent%
    Address: %Client.*.Addr%
    Requested URL: %Client.*.Session.*.PlayerRequestedURL%

### Report Output

Once you've defined your template and applied the changes, Helix Universal Server sends the custom logging information to the chosen output each time a client connects or disconnects. The following is an example of a single media player connecting, then disconnecting.

    ****CLIENT REQUEST****
    Date and Time: 06/19/02, 14:53.51
    **CLIENT INFORMATION**
    Type: RealMedia Player Version 6.0.9.1349 (win32)
    Address: 207.188.7.125
    Total Bandwidth: 57600
    Preferred Language: es, *
    **CLIP INFORMATION**
    Requested URL: rtsp://208.147.89.157:554/video1.rm
    Clip Size in Bytes: 2479645
    Title: Introductory Video
    Author: RealNetworks, Inc.
    Copyright: ©2002 RealNetworks, Inc.
    Stream Count: 1
    **TRANSPORT INFORMATION**
    Protocol: RTSP
    Port: 7180
    UDP used (0=no, 1=yes): 1

    ****CLIENT DISCONNECT****
    Date and Time: 06/19/02, 14:59.15
    Type: RealMedia Player Version 6.0.9.1349 (win32)
    Address: 207.188.7.125
    Requested URL: rtsp://208.147.89.157:554/video1.rm

| © 2002 RealNetworks, Inc. All rights reserved. For more information, visit RealNetworks Click here if the Table of Contents frame is not visible at the left side of your screen.